Release 10.1A: OpenEdge Development:
Progress 4GL Reference

PROCEDURE statement

Declares an internal procedure.

Syntax

PROCEDURE proc-name [ EXTERNAL "dllname" [ CDECL | PASCAL | STDCALL ] [ ORDINAL n ] [ PERSISTENT ] ] [ PRIVATE ] [ IN SUPER ]

proc-name

The name of the internal procedure.

EXTERNAL "dllname"

Identifies the internal procedure as a Windows dynamic link library (DLL) routine or a UNIX shared library routine. The dllname argument, specified as a string literal, is the name of the DLL or library containing the routine.

CDECL

Tells Progress to use the C calling convention when accessing the routine.

PASCAL

Supported only for backward compatibility.

STDCALL

Tells Progress to use the standard Windows calling convention when accessing the routine. This is the default.

ORDINAL n

Specifies the number of the DLL entry point (the nth routine) to invoke. If you use the ORDINAL option, then proc-name can specify any name used in the corresponding RUN statement to reference the routine. If you omit the ORDINAL option, proc-name specifies which DLL routine you want to invoke.

PERSISTENT

Specifies that the DLL or shared library routine should remain loaded in memory until Progress exits or the session executes the RELEASE EXTERNAL statement.

PRIVATE

Indicates the following about the internal procedure:

That it cannot be invoked from an external procedure—that is, from a procedure file external to the current procedure file.
That the INTERNAL-ENTRIES attribute on the procedure that defines it does not provide its name (unless the procedure that defines it is the current procedure file).
That the GET-SIGNATURE method on the procedure that defines it does not provide its signature (unless the procedure that defines it is the current procedure file).

IN SUPER

Indicates that the definition of the internal procedure resides in a super procedure. For more information on super procedures, see OpenEdge Development: Progress 4GL Handbook .

Examples

The following example declares a Progress internal procedure that computes the factorial of an integer entered as an INPUT parameter. The result is returned as an OUTPUT parameter. Note that the following procedure calls itself recursively to obtain the result:

r-factrl.p

DEFINE VARIABLE FactorialResult AS INTEGER FORMAT ">>>,>>>,>>9". DEFINE VARIABLE FactorialInput AS INTEGER. REPEAT: SET FactorialInput VALIDATE(FactorialInput <= 12 AND FactorialInput >= 0, "Value must be between 0 and 12."). RUN Factorial (INPUT FactorialInput, OUTPUT FactorialResult). DISPLAY FactorialResult. END. PROCEDURE Factorial: DEFINE INPUT PARAMETER PTerm AS INTEGER. DEFINE OUTPUT PARAMETER FactorialResult AS INTEGER. DEFINE VARIABLE WorkingResult AS INTEGER. IF PTerm <= 1 THEN DO: FactorialResult = 1. RETURN. END. ELSE DO: RUN Factorial (INPUT PTerm - 1, OUTPUT WorkingResult). FactorialResult = PTerm * WorkingResult. END. END PROCEDURE.

The following example declares a DLL routine, MessageBox(), which displays a message:

r-dllex1.p

DEFINE VARIABLE result AS INTEGER. MESSAGE " It’s a whole new world!" VIEW-AS ALERT-BOX MESSAGE BUTTONS OK TITLE "Progress Message". RUN MessageBoxA (0, " It’s a whole new world, again!!", "Progress DLL Access", 0, OUTPUT result). PROCEDURE MessageBoxA EXTERNAL "user32.dll": DEFINE INPUT PARAMETER hwnd AS LONG. DEFINE INPUT PARAMETER mbtext AS CHARACTER. DEFINE INPUT PARAMETER mbtitle AS CHARACTER. DEFINE INPUT PARAMETER style AS LONG. DEFINE RETURN PARAMETER result AS LONG. END.

Notes

You can terminate a PROCEDURE statement with either a period (.) or a colon(:).
You can place an internal procedure before, after, or in the middle of your main procedure code. You cannot nest an internal procedure within another internal procedure.
Use the RUN statement to invoke an internal procedure. You can run an internal procedure from within the external procedure that defines it, either from the main-line of the external procedure or from another internal procedure defined in the external procedure. You can also run an internal procedure defined in another external procedure using the IN proc-handle option of the RUN statement as long as the external procedure meets one of these conditions:
It is active on the procedure call stack.
It is an instance of a persistent procedure.
If you declare the internal procedure as a Progress 4GL procedure, the body of the procedure can contain zero or more 4GL statements. These statements can include definitions of run-time parameters (using the DEFINE PARAMETER statement), local program variables, frames, widgets, and buffers. Any such objects you define within the internal procedure remain in effect only for the life of the internal procedure.

If you are defining the internal procedure for use as an event procedure to handle asynchronous remote requests, you can specify run-time parameters as INPUT only. (Any other type of parameter generates a run-time error.) Each INPUT parameter must correspond in order and data type with an OUTPUT (or INPUT-OUTPUT) parameter as defined in the remote procedure that executes the request. For more information on working with asynchronous remote requests and event procedures, see OpenEdge Application Server: Developing AppServer Applications .

You cannot define shared objects, work tables, or temporary tables within an internal procedure.
An internal procedure can reference any objects defined in the outer procedure block. For example, it can reference variables, buffers (explicit or implicit; shared or unshared), variables, run-time parameters, named frames, or temporary tables. If you define an object with the same name in the internal procedure and the external procedure, a reference within the internal procedure resolves to the local object.
A buffer explicitly defined in an internal procedure is scoped to the internal procedure. Any other buffers are scoped to the outer procedure block.
If you declare the internal procedure as a DLL or UNIX shared library routine (use the EXTERNAL option), the body of the procedure can contain zero or more DEFINE PARAMETER statements.
For more information on accessing DLL or UNIX shared library routines from Progress, see the chapter on DLLs in OpenEdge Development: Programming Interfaces .
To define the internal procedure as an event handler for ActiveX controls (OCX event procedure), you must specify proc-name according to the following syntax:

{ control-frame-name .control-name .event-name | ANYWHERE .event-name }

In control-frame-name.control-name.event-name, control-frame-name is the name (unquoted) of the control-frame that contains the ActiveX control. This is the name that the AppBuilder typically assigns to the control-frame (NAME widget attribute) when you insert the control into your user interface. The control-name is the value (unquoted) that you assign to the control Name property at design time in the AppBuilder Property Window. The event-name is the name (unquoted) of the ActiveX control event that you want to trigger execution of this procedure.

In ANYWHERE.event-name, ANYWHERE specifies an event procedure that handles the specified event in any ActiveX control. This event procedure executes only if you have not defined a control-frame-name.control-name.event-name event procedure that exactly matches the control/event combination at run time.

At design time, the AppBuilder lists the available events for a control and automatically creates a template for the OCX event procedure definition from the event that you select. For more information on how to create OCX event procedures in the AppBuilder, see the information on ActiveX controls in OpenEdge Development: Programming Interfaces . For more information on how to work with OCX event procedures in an application, see OpenEdge Development: Programming Interfaces .

When you define an OCX event procedure, you can access the component handle (COM-HANDLE value) of the control that generates the event at run time using the COM-SELF system handle. You can also access the widget handle of the parent control-frame using the SELF system handle.
The RETURN-VALUE function provides the value returned by the most recently executed RETURN statement of a local or remote procedure.
For SpeedScript, the only invalid option is PASCAL.
You can declare an internal procedure as a routine in a UNIX shared library in the same manner as declaring a DLL routine. The one exception is that the ORDINAL option is not applicable to UNIX and will be ignored. For example:

PROCEDURE atoi EXTERNAL "/usr/lib/libc.so.1": . . .

On 64-bit platforms, long integers passed from a shared library to Progress will lose their upper four bytes.

See also

COM-SELF system handle, DEFINE PARAMETER statement, END statement, RUN statement, TRIGGER PROCEDURE statement